% html: Beginning of file: `gccgo_install.html'
%  Setting up and using gccgo 
\chapter{Install GCCGo}
\label{chap:gccgoinstall}
This document explains how to use \texttt{gccgo}, a compiler for
the Go language.  The \texttt{gccgo} compiler is a new frontend
for \texttt{gcc}, the widely used GNU compiler.  Although the
frontend itself is under a BSD-style license, \texttt{gccgo} is
normally used as part of \texttt{gcc} and is then covered by
the GNU General Public
License\footnote{See URL http://www.gnu.org/licenses/gpl.html}.

Note that \texttt{gccgo} is not the \texttt{6g} compiler; see
the Installing Go instructions for that
compiler.

\section{Source code}

\label{f0}
The \texttt{gccgo} source code is accessible via Subversion.  The
\texttt{gcc} web site
has instructions for getting the
\texttt{gcc} source code\footnote{See URL http://gcc.gnu.org/svn.html}.  The \texttt{gccgo} source code
is a branch of the main \texttt{gcc} code
repository: \texttt{svn://gcc.gnu.org/svn/gcc/branches/gccgo}.

\section{Building}


Building \texttt{gccgo} is just like building \texttt{gcc}
with one additional option.  See
the instructions on the gcc web
site\footnote{See URL http://gcc.gnu.org/install/}.  When you run \texttt{configure}, add the
option \texttt{--enable-languages=c,c++,go} (along with other languages you
may want to build).

A number of prerequisites are required to build \texttt{gcc}, as
described on the \texttt{gcc} web site.  If those are all
available, then a typical build and install sequence would look like
this:
\begin{verbatim} 
svn checkout svn://gcc.gnu.org/svn/gcc/branches/gccgo gccgo
mkdir objdir
cd objdir
../gccgo/configure --enable-languages=c,c++,go
make
make install
\end{verbatim}

\section{Using gccgo}


The \texttt{gccgo} compiler works like other gcc frontends.

To compile a file:
\begin{verbatim} 
gccgo -c file.go
\end{verbatim}

That produces \texttt{file.o}. To link files together to form an
executable:
\begin{verbatim} 
gccgo -o file file.o
\end{verbatim}

To run the resulting file, you will need to tell the program where to
find the Go runtime library. This can be done either by setting
\texttt{LD\_LIBRARY\_PATH} in your environment:
\begin{verbatim} 
LD_LIBRARY_PATH=/usr/lib/gcc/MACHINE/VERSION
\end{verbatim}

or by passing a \texttt{-Wl,-R} option when you link:
\begin{verbatim} 
gccgo -o file file.o -Wl,-R,/usr/lib/gcc/MACHINE/VERSION
\end{verbatim}

or you can use the \texttt{-static-libgo} link-time option to link
statically against libgo, or you can do a fully static link (static
linking is the default for the \texttt{6l} Go linker).  On most
systems, a static link will look something like:
\begin{verbatim} 
gccgo -o file file.o -static -L /usr/lib/nptl -lgobegin -lgo -lpthread
\end{verbatim}

You may get a warning about not creating an \texttt{.eh\_frame\_hdr}
section; this has nothing to do with Go, and may be ignored. In the
future the requirement of explicitly specifying
\texttt{-L /usr/lib/nptl -lgobegin -lgo -lpthread}
may be removed.

\section{Imports}


When you compile a file which exports something, the export
information will be stored directly in the object file. When
you import a package, you must tell \texttt{gccgo} how to
find the file.

When you import the package \textsl{FILE} with \texttt{gccgo},
it will look for the import data in the following files, and use the
first one that it finds.
\begin{itemize}
\item \texttt{\textsl{FILE}.gox}
\item \texttt{\textsl{FILE}.o}
\item \texttt{lib\textsl{FILE}.so}
\item \texttt{lib\textsl{FILE}.a}
\end{itemize}

\texttt{\textsl{FILE}.gox}, when used, will typically contain
nothing but export data. This can be generated from
\texttt{\textsl{FILE}.o} via
\begin{verbatim} 
objcopy -j .go_export FILE.o FILE.gox
\end{verbatim}

The \texttt{gccgo} compiler will look in the current
directory for import files. In more complex scenarios you
may pass the \texttt{-I} or \texttt{-L} option to
\texttt{gccgo}. Both options take directories to search. The
\texttt{-L} option is also passed to the linker.
The \texttt{gccgo} compiler does not currently (2009-11-06) record
the file name of imported packages in the object file. You must
arrange for the imported data to be linked into the program.
\begin{verbatim} 
gccgo -c mypackage.go              # Exports mypackage
gccgo -c main.go                   # Imports mypackage
gccgo -o main main.o mypackage.o   # Explicitly links with mypackage.o
\end{verbatim}

\section{Unimplemented}


Some Go features are not yet implemented in \texttt{gccgo}.  As of
2009-11-06, the following are not implemented:
\begin{itemize}
\item Garbage collection is not implemented. There is no way to free memory.
    Thus long running programs are not supported.
\item goroutines are implemented as NPTL threads with a fixed stack size.
    The number of goroutines that may be created at one time is limited.
\end{itemize}

\section{Debugging}


If you use the \texttt{-g} option when you compile, you can run
\texttt{gdb} on your executable.  The debugger doesn't (yet)
know anything about Go. However, you can set breakpoints, single-step,
etc.  You can print variables, but they will be printed as though they
had C/C++ types. For numeric types this doesn't matter. Go strings
will show up as pointers to structures; to see the value
\texttt{print *stringvar}. In general Go strings, maps, channels
and interfaces are always represented as C pointers.

\section{C Interoperability}


When using \texttt{gccgo} there is limited interoperability with C,
or with C++ code compiled using \texttt{extern {\tt{}"{}}C{\tt{}"{}}}.

\subsection{Types}


Basic types map directly: an \texttt{int} in Go is an \texttt{int}
in C, etc. Go \texttt{byte} is equivalent to C \texttt{unsigned char}.
Pointers in Go are pointers in C. A Go \texttt{struct} is the same as C
\texttt{struct} with the same fields and types.

The Go \texttt{string} type is a pointer to a structure.
The current definition is
(this is \textbf{expected to change}):
\begin{verbatim} 
struct __go_string {
  size_t __length;
  unsigned char __data[];
};
\end{verbatim}

You can't pass arrays between C and Go. However, a pointer to an
array in Go is equivalent to a C pointer to the
equivalent of the element type.
For example, Go \texttt{*\mbox{$[$}10\mbox{$]$}int} is equivalent to C \texttt{int*},
assuming that the C pointer does point to 10 elements.

A slice in Go is a structure.  The current definition is
(this is \textbf{subject to change}):
\begin{verbatim} 
struct __go_slice {
  void *__values;
  int __count;
  int __capacity;
};
\end{verbatim}

The type of a Go function with no receiver is equivalent to a C function
whose parameter types are equivalent. When a Go function returns more
than one value, the C function returns a struct. For example, these
functions have equivalent types:
\begin{verbatim} 
func GoFunction(int) (int, float)
struct { int i; float f; } CFunction(int)
\end{verbatim}

A pointer to a Go function is equivalent to a pointer to a C function
when the functions have equivalent types.

Go \texttt{interface}, \texttt{channel}, and \texttt{map}
types have no corresponding C type (they roughly correspond to pointers
to structs in C, but the structs are deliberately undocumented). C
\texttt{enum} types correspond to some Go type, but precisely
which one is difficult to predict in general; use a cast. C \texttt{union}
types have no corresponding Go type. C \texttt{struct} types containing
bitfields have no corresponding Go type. C++ \texttt{class} types have
no corresponding Go type.

Memory allocation is completely different between C and Go, as Go uses
garbage collection. The exact guidelines in this area are undetermined,
but it is likely that it will be permitted to pass a pointer to allocated
memory from C to Go. The responsibility of eventually freeing the pointer
will remain with C side, and of course if the C side frees the pointer
while the Go side still has a copy the program will fail. When passing a
pointer from Go to C, the Go function must retain a visible copy of it in
some Go variable. Otherwise the Go garbage collector may delete the
pointer while the C function is still using it.

\subsection{Function names}


Go code can call C functions directly using a Go extension implemented
in \texttt{gccgo}: a function declaration may be followed by
\texttt{\_\_asm\_\_({\tt{}"{}}NAME{\tt{}"{}})}. For example, here is how the C function
\texttt{open} can be declared in Go:
\begin{verbatim} 
func c_open(name *byte, mode int, perm int) int __asm__ ("open");
\end{verbatim}

The C function naturally expects a nul terminated string, which in
Go is equivalent to a pointer to an array (not a slice!) of
\texttt{byte} with a terminating zero byte. So a sample call
from Go would look like (after importing the \texttt{os} package):
\begin{verbatim} 
var name = [4]byte{'f', 'o', 'o', 0};
i := c_open(&name[0], os.O_RDONLY, 0);
\end{verbatim}

(this serves as an example only, to open a file in Go please use Go's
\texttt{os.Open} function instead).

The name of Go functions accessed from C is subject to change. At present
the name of a Go function that does not have a receiver is
\texttt{package.Functionname}. To call it from C you must set the
name using a \texttt{gcc} extension similar to the \texttt{gccgo}
extension.
\begin{verbatim} 
extern int go_function(int) __asm__ ("mypackage.Function");
\end{verbatim}

\subsection{Automatic generation of Go declarations from C source code}


The Go version of \texttt{gcc} supports automatically generating
Go declarations from C code. The facility is rather awkward at present,
and a better mechanism is under development.

Compile your C code as usual, but replace \texttt{-c} with
\texttt{-S\* -ggo}. The result will be an assembler file
with a \texttt{.s} extension. This assembler file will contain
comments beginning with \#GO. Those comments are declarations in the Go
language for the C types, variables and functions declared in the C code.
C types which can not be represented in Go will contain the string INVALID.
Unsupported macro definitions will be recorded as \texttt{unknowndefine},
and uses of \texttt{\#undef} will be recorded as \texttt{undef}.
So it is very approximately possible to get Go code by running
\begin{verbatim} 
gcc -S -ggo foo.c
grep '#GO' foo.s | grep -v INVALID | grep -v unknowndefine | grep -v undef > foo.go
\end{verbatim}

This procedure is full of unstated caveats and restrictions and we make no
guarantee that it will not change in the future. It is more useful as a
starting point for real Go code than as a regular procedure.
% html: End of file: `gccgo_install.html'
